# 🤖 Full Agent + Streamlit - OSS Chatbot Workshop

Complete Streamlit application with LangChain agent, multiple tools, and RAG (FAISS).

---

## 📋 Table of Contents

1. [Overview](#overview)
2. [Prerequisites](#prerequisites)
3. [Installation](#installation)
   - [Option 1: Docker (Recommended)](#option-1-docker-recommended)
   - [Option 2: Windows Native](#option-2-windows-native)
   - [Option 3: macOS Native](#option-3-macos-native)
4. [Execution](#execution)
5. [Project Structure](#project-structure)
6. [Troubleshooting](#troubleshooting)

---

## 🎯 Overview

This is the workshop's production application, combining:
- ✅ **Streamlit** for the web interface
- ✅ **LangGraph**: Orchestrates the agent workflow as a **Cyclic Supervisor Graph** (Multi-step reasoning).
- ✅ **Ollama** for local LLMs
- ✅ **RAG with FAISS** for knowledge search
- ✅ **Multiple tools** (calculation, summarization, RAG)

---

## 📦 Prerequisites

### Essential (for all options):
- **Ollama** installed and running
- **llama3.1** model downloaded in Ollama (supports tool calling)

### For Docker:
- **Docker Desktop** installed
- 4GB RAM available
- 2GB disk space

### For local installation:
- **Python 3.11 or 3.12**
- **pip** (standard) or **Poetry** (optional)

---

## 🚀 Installation

We have organized the installation process by Operating System to make it easier for you.

### Option 1: Docker (Recommended) 🐳

Docker ensures an **isolated environment** and **full compatibility**.

1.  **Install Docker Desktop**
    *   [Windows/Mac/Linux Download](https://www.docker.com/products/docker-desktop)
2.  **Start Ollama** (System-level)
    *   Make sure `ollama serve` is running on your host machine.
    *   Pull the model: `ollama pull llama3.1`
3.  **Run the Helper Script**
    *   **Mac/Linux:**
        ```bash
        chmod +x docker-run.sh
        ./docker-run.sh run
        ```
    *   **Windows:**
        Run `docker-compose up --build` in PowerShell.

4.  **Access:** http://localhost:8501

---

### Option 2: Windows (Native) 💻

We provide automated scripts to handle dependencies.

#### 1. System Setup
Run the `install.ps1` script to install system dependencies (C++ Redistributable, Ollama, Graphviz):
```powershell
.\setup\windows\install.ps1
```

#### 2. Python Setup
```powershell
# Create virtual environment (recommended)
python -m venv .venv
.\.venv\Scripts\activate

# Install libraries
pip install -r requirements.txt
```

#### 3. (Optional) GPU Acceleration
If you have an NVIDIA GPU, fix PyTorch to use CUDA:
```batch
.\setup\windows\fix_pytorch_cuda.bat
```

#### 4. Run Locally
```powershell
streamlit run ui.py
```

---

### Option 3: macOS (Native) 🍎

#### 1. System Setup
Use the script to install dependencies via Homebrew (Graphviz, Ollama):
```bash
chmod +x setup/mac/install.sh
./setup/mac/install.sh
```

#### 2. Python Setup
```bash
# Create virtual environment (recommended)
python3 -m venv .venv
source .venv/bin/activate

# Install libraries
pip install -r requirements.txt
```

#### 3. Run Locally
```bash
streamlit run ui.py
```

---

## 🎮 Execution

### Typical Workflow

1. **Ensure Ollama is running:**
   ```bash
   ollama serve
   ```

2. **Verify llama3.1 model:**
   ```bash
   ollama list
   ```

3. **Run application:**
   
   **With Docker:**
   ```bash
   ./docker-run.sh run
   ```
   
   **Locally (after venv activation):**
   ```bash
   streamlit run ui.py
   ```

4. **Access in browser:**
   http://localhost:8501

---

### ⚙️ Interactive Configuration (Setup Tab)

The application features a dedicated **Setup Tab** for real-time configuration:

*   **LLM Controls:** Adjust Temperature, Context Window, and Max Tokens.
*   **RAG Settings:** Configure Chunk Size and Overlap.
*   **Persistence:** Toggle conversation history saving to SQLite.
*   **Save:** Changes are saved to `config/model_config.yaml`.

---

## 📁 Project Structure

```
Full Agent + streamlit/
├── setup/                     # 📂 INSTALLATION SCRIPTS (New)
│   ├── windows/               # Windows specific setup
│   └── mac/                   # MacOS specific setup
├── Dockerfile                 # Docker configuration
├── docker-compose.yml         # Docker orchestration
├── docker-run.sh              # Docker helper script
├── requirements.txt           # Python dependencies
├── ui.py                      # Main Streamlit interface
├── config/                    # Configuration files
├── docs/                      # Documentation
├── src/                       # Source code
├── tests/                     # Tests
└── data/                      # Data directory
```

---

## 🛡️ Security and Quality

The architecture implements a **Two-Layer Safety System**:

### 1. Moderation Layer ("The Police")
*   **Location:** `src/moderation/manager.py`
*   **Checks:** Toxicity, Injection, PII Masking, DLP.

### 2. Guardrails ("The Conduct Manual")
*   **Location:** `src/guardrails/validators.py`
*   **Checks:** Citations, Tone.

---

## 🔧 Troubleshooting

### Docker
*   **"Cannot connect to Docker daemon":** Start Docker Desktop.
*   **"port 8501 already in use":** Kill process using port 8501 or change port in `docker-compose.yml`.
*   **"Ollama connection refused":** Ensure `ollama serve` is running. Use `host.docker.internal` in container.

### App
*   **"FAISS index not found":** Run `python src/rag/generate_vector_db.py`.
*   **Interface not loading:** Clear cache (`rm -rf ~/.streamlit/`) or check logs.

---

## 🎓 Tips for Workshop

1.  **Preparation:** Install Docker and pull `llama3.1` beforehand.
2.  **During:** Use Docker for a uniform experience.
3.  **Debug:** Check terminal logs for backend errors.

---

## 👨‍💻 Author

**Givaldo**

---

**Ready for the Workshop! 🚀**
